U++ forum: Welcome to the forum

Re: Documentation how-to... [message #17951 is a reply to message #17751]

Thu, 04 September 2008 10:32

cbpporter
Messages: 1401
Registered: September 2007

Ultimate Contributor

I decided to sit down and write a documentation page to see how hard it is and how Topic++ could be improved.

So actually writing the content is not that hard, but formatting the page is. It takes a lot more time when compared to filling in the content.

First some issues:
1. The text in Topic++ is too large. Just in the editor. When previewing the page, it is rendered with the normal size for the font that was given.
2. When I insert a table and drag it's left side a little to the left in the editor, in the preview mode the table position and size is all wrong.
3. Copy pasting from Topic++ to OpenOffice inserts some extra characters. I guess it is because of hidden formating fields or something.

Also some interface issues:
4. Insert table does not remember your previous options. I am not going to insert 10 different types of tables in a documentation page because of consistency. So if the default is not good, I have to change the options for each table.
5. Neither does Query nor Hyperlink remember my last position.
6. Inserting a function definition with Query kills my paragraph indent.
7. Inserting a function definition with Query will add String with ::String hyperlink, which points nowhere. Changing it is hard because you have to navigate to Core/src/String for every item.

And of course:
8. I know this came up before, but "src" and "srcdoc" have got to go. Why not rename them to "Reference" and "Manual" or something. Also, if you really want to keep these cryptic names, at least use capital letters. In a tree list there is nothing more unaesthetic that having a lower case leaf between full English text leaves, i.e. "Used Packages/Core/srcdoc/Doing some neat stuff".
9. And these 3 categories are not necessarily the best ones. The example of a possible documentation page that I attached does not fit that well in src, because it is just a bunch of functions with the title of the page and their logical connection the only thing that links them together. It does not fit in srcdoc, because it more like a reference.

Also, after creating this page, I though about a different layout. But manually changing it is tedious. A way to change stuff like CSS is used for web pages would simplify thing a lot. Maybe some tables with interchangeable styles.

Here is a test documentation page. It is not complete and uses some weird colors for headers. It is just a test. But we should settle on the style of a documentation page.

Edit: removed old attachment.

[Updated on: Thu, 04 September 2008 15:31]

Report message to a moderator