Forum OpenACS Development: Re: 4.6.x Documentation; Documentation formatting

Collapse
3: Re: 4.6.x Documentation; Documentation formatting (response to 1)
Posted by Ola Hansson on 02/20/03 11:29 AM
Joel,

Those sound like really useful additions indeed!

To comment on your questions:

2) Personally, I think I prefer the current style (probably mostly because I've grown acustomed to it). I find the new style a little muddled 😊

3) Hmm.. I can see your point that cutting/pasting should be easy. However, I think we ought to focus on readability, and keeping the prompts makes it much easier for the installer to realize from where and as which user a certain command should be issued. The "first-timer" is probably more anxious about gaining understanding of what's going on during the installation than (s)he is about gaining time.

4) I don't think anyone will object to this.

Collapse
4: Re: 4.6.x Documentation; Documentation formatting (response to 3)
Posted by Jamie Rasmussen on 02/20/03 12:45 PM
I also prefer the current style overall - in particular, I don't like things that look like buttons that I can't click on. I do think some of your enhancements are nice. I think giving the user a few action cues with color is great if not overused. We should also check that users with color vision deficiency won't have problems with readability.

In my Windows install documents, I took a cut-and-paste approach, and it has been very useful. You can put comments in with, e.g. 

# Aren't you glad you can cut-and-paste this command?
/usr/local/bin/tcpserver -x /etc/tcp.smtp.cdb -v -u 502 -g 501 0 smtp /var/qmail/bin/qmail-smtpd 2>&1 | /var/qmail/bin/splogger smtpd 3 &

You could make commands and comments different colors, white and green perhaps. Of course you would still lose any inlined output and prompt information as Ola mentioned. Thanks for working on this!

Collapse
5: Re: 4.6.x Documentation; Documentation formatting (response to 4)
Posted by Jeff Davis on 02/20/03 01:15 PM
I would say that even if this is readable by people we should avoid the bright green on bright yellow since it is very likely to make peoples brains explode :)

I am a big fan of cut and paste things as well. One example of something we might consider is the oracle setup statements page that Lars did. I use it all the time...