- How to avoid isolated pages ?
Doesn’t concern Class Helpfiles. Typically, the Glossary or Introduction to GUI, which I think might be difficult to reach.
Maybe I’m wrong about this, and this is due to the way I’m browsing help. I realized I was using it like a wiki, only navigating through the searchbar, or via links, but never using the arborescence to navigate back-and-forth through topics.
If you don’t know the Glossary page exists, the only way you reach it is using Browse > Help > Glossary. I find the Document Browser quite unfriendly.
But I think the response to the problem (if it is a common problem, not only mine) isn’t a specific guideline about multiplying references to a file, but a better arborescence representation within SCDoc UI.
- Gimme summary
I liked the old Wikipedia style:
First, it would help navigate. Second, it would give a direct representation of what topics should be (ideally) covered within a ‘standard’ helpfile. Contributors to the SCDoc will likely have navigated the documentation for hours before contributing. They would have seen this summary dozens of times. They would know what’s expected.
- Collapsable blocs of text
Maybe off-topic, but...
…there’s this issue between being brief and concise, and overexplaining things. I’ve spent a lot of times debugging special cases that weren’t documented. Showing equations on the helpfile is a must, but might scare newcomers. I’d like to provide copy-paste templates, but I don’t want them to pollute the helpfile by default.
So I don’t know if we have this collapsable bloc of text functionality available in the SCDoc renderer, but I think this is a good answer to the problems mentionned above.