Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Ticket #1176 (assigned defect)

Opened 3 months ago

Last modified 3 months ago

Manual, API docs, examples and tutorials, per function/class wiki pages -> total confusion

Reported by: elite01 Assigned to: larsivi (accepted)
Priority: major Milestone: Documentation
Component: Documentation Version:
Keywords: Cc:

Description

There's mostly nice API documentation generated from the source code. There are nice tutorials that really helped me. There's also a manual I never took a look at. Then, there's a wiki page per function or class, linked from the API docs. It seems I'm the only one who wrote any of significance. Also, there are examples all over the place.

If this sounds confusing, then it probably is. This really has to be clearly documented - what goes where, where do I look if I need what - and this document should be easily accessible (from the front page?). Otherwise, people looking for documentation (anyone using Tango) won't know where to look and will be confused. That also applies to people who want to write documentation - I find the wiki comfortable for that, but the confusion remains.

Change History

07/06/08 09:58:33 changed by Cyborg16

The way I see it is that the source and Ddoc documentation provides the most up-to-date API reference, while the manual and wiki provide a little more info on the overall design. But don't take my word for it; I'm not a developer.

IIRC there's been more than one request for the documentation to be downloadable for offline reading; this might be a reason to have less of the documentation on the wiki?

07/06/08 10:34:21 changed by larsivi

  • status changed from new to assigned.

I understand what elite01 says, and intend to rectify his confusion :) There is no perfect solution, but API docs are indeed easier to keep up-to-date.

The download aspect isn't much of a problem as you can see if you test the .chm files available from this page.

If anything, I would like better tools from generating docs from source though. Ddoc doesn't fully cut it yet.

Roadmap Timeline Tickets New Ticket Help / Guide About Trac
Login  |  
Trac dsource.org
RSS
Copyright © 2006-2008 Tango. All Rights Reserved. | Page Width: Static or Dynamic