[haiku-doc] Re: Installation docs with css and javascript

Hello Humdinger, happy to hear you liked the docs. It was a long process to 
format and edit all those docs. I wrote a couple of guides and lines myself, or 
completed them with information in comments, but it was basically a gathering 
job.  I was wondering, are you the only person working on documentation, if 
not, hello everyone on the list?

> > I've included the edits to the css I talked about earlier. I also use a 
> > small 
> script,
> > which loads pages in a new window/tab since xhtml strict doesn't allow 
> rel="_blank".
> > This could be used by anybody who needs to link to external websites (just 
> > add
> > rel="external" to your statements).
> 
> Well... I don't think it's needed. Personally, I hate when websites shove 
> link 
> behaviour down my throat. IMO a link should always simply take me to the 
> linked 
> site. If I want to open it in another window/tab, I middle-click or use a 
> modifier key or the context menu or however I configured my browser.
> So, I'd vote against inconsistent link behaviour.

No problem, I know there are two schools of thought about external links, and 
since your pretty much the project manager ;) I'd say no problem. When the docs 
are checked in, I'll remove all the rel=external attributes of my links. It'll 
take 2 seconds (I use textmate, and it's very easy to find/replace text inside 
projects. So if there is general cleaning to do, just say it and I'll process 
the stuff).

> > So, on another note, when will we see the UserGuide on the Haiku website :D
> 
> Good question. I don't feel like prodding again on the web mailing list... 
> And 
> it looks like the wiki-like test site that could also help with translations 
> is 
> still some time away. Let's give it a bit more time.

O.K. for now, maybe we could think of a target? Like Alpha or Beta. Obviously 
at R1 everything will be on the website. What has been your replies on the 
weblist?

> > This has
> > become fairly important, since some of the writers from which I used help 
> guides could
> > edit the UserGuide directly, and remove their old documents from the site. 
> More
> > visibility and more editing the guide... great!
> 
> BTW, we should at least put the original authors in the author comment of 
> each 
> respective page.

Yes, I intended to do that, but didn't know where to put the credits. I forgot 
to ask about it (all the authors have been advised that there names would 
figure somewhere... I didn't know where :). When you say author comment, you 
mean in the header or something (like the css). If not, could you point me to 
an example. I thought about including name and last edit date either under the 
title or at the bottom of the pages, in light grey or something. It would be 
nice.

> Are you interested to further improve the installation section? (Of course, 
> wait 
> first until I checked the current version in.)

Yes, I hope to continue help on the documentation (especially since you seem to 
be all alone). I will try to fit in all the needed work for my docs, and once 
it's looking good, I'll pick an easy application and start some writing on 
that. All my work is stopped until the docs are in the svn repo.

> I think it would be good to have the installation.html as a sort of 
> "contents" 
> page for the different installation methods. So, after the current small 
> introduction headers with another short intro to the topic and a link to 
> the actual page.

What format/style are you thinking of? Something like the contents pages where 
info is on the right, or a list, with sub lists. ex.

- Title
       - Subtitle
    - Subtitle

Description text...

> That way, we could also avoid duplication of e.g. GRUB configuration.
> If you want to, I can make a quick stubbed version that will illustrate what 
> mean.

I was already thinking about something like this, where general
information would be on a separate page (for ex. building from source,
put the UserBuildConfig and grub stuff on the installation-source.html
so writers can simply link there. Check the code for my todo on that
page). This could and should be pushed further.

I would appreciate a stub or something, I'm not sure I get this right. The 
reason I sent these documents right now is that I knew you'd have good ideas 
for layout and organization. So I am open to all these propositions. I just 
didn't have any ideas left for content indexing and stuff.

Thank you for the kind words, and I would say the same to you. Your doing an 
incredible job :)
Socapex_2K



      __________________________________________________________________
Instant Messaging, free SMS, sharing photos and more... Try the new Yahoo! 
Canada Messenger at http://ca.beta.messenger.yahoo.com/

Other related posts: