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

NOTE: Out of date

Some of the information here may still be of interest, but most, if not all, should be possible to find in other parts of the site.

Short Term Goals

What we're after is a slick set of documentation: inviting, accessible, and dynamic. The idea is to combine the best of traditional source-code documentation, with dynamic user-driven Wiki style commentary and examples. The whole affair is intended to be fronted with a slick veneer, in the shape of a blog; or something similar.

The underlying code-content is to be aggregated from various dsource projects, effectively becoming 'unified' under the documentation shell. This has been described as a "meta project".

We should also try to establish a set of "common practices", exemplified by the initial submissions

Long Term Goals

A world-class, cohesive and coherent suite of libraries and documentation, for the D programming language.

Wiki Setup

A wiki is needed for quick and dirty addition of information, particularly for API docs annotations. It might also be possible to use the wiki for deeper documentation, as a wholesale documentation site, then in the meaning as a manual. Which wiki should we use?

  • DSource with Trac : This would have to be set up as a new project at DSource, possibly without a svn repository, unless there are docs/other things that cover more than one of the participating projects. Pro for this solution is that Trac at some point (might already be possible) will gain intertrac wikilinks, meaning we could get almost 100% between the wikis of the participating projects. Trac also has the added value features ticket system and roadmap. Brad has setup a Trac project here: http://www.dsource.org/projects/tango
  • External with what would most likely be MediaWiki? (powerful, and no camelcase): Pro for this is that it won't have the trac feel which possibly can pull some attention away from the project itself, but this is a minor issue in larsivi's opinion (and Kris' also). Peri points out that MediaWiki? has a tabbed layout, and thus tends to look less cluttered.

Generated API Documentation

We need high quality doc output. DDoc gets us part of the way with docs that can be stylized. CandyDoc? AJAX'ifies this further and is currently the best solution available. Some hacking and testing have led to symbols that are linkable into the wiki, for annotations that might later be migrated into the docs proper, or kept in the wiki if usable as suggestions, etc.

  • Someone must write awesome CSS, candidates are
    • Kyle, Charlie; possibly Nick or David Gileadi?
  • The creator of CandyDoc?, Victor, would be nice to have onboard
  • Improvements ideas
    • Could probably use hover actvity on LHS
  • As much information in the docs as possible should be linked to other parts, all symbols, preferably keywords, etc (medium term, might depend on better tools)
  • It would be nice if the package structure/or inheritance could be reflected in the url (must make a choice here). Diagrams might be a solution for the inheritance part, I think package structure should be used for the url since D don't have to be OO. <-- Lars Ivar's opinion

Blog Front

A slick front-end for the project is needed, a CMS/Blog is probably the quickest and easiest setup to get online with a respectable result.

  • Which CMS/Blog:
    • Drupal: Lars Ivar have tried this for two sites, thinks it's good, and even more for sites with more info than just news items. Also has bindings to MediaWiki?.
    • Wordpress: Charles has experience with this, definately good for just the newsitems
  • Where:
    • Probably cheap, hosted solution, unless someone can dedicate a server/bandwidth
    • Brad has offered to host this and since this would give us better control over the server it might be a better solution than a cheap hoster and Brad wants to contribute. If traffic surges, we might have to consider a dedicated server in any case.
  • Who: Someone who wants do dedicate time to the upkeep/mantainance of the site, probably Charles or Kyle ?
  • Content
    • News items
    • Articles
    • RSS aggregator in corner for collecting the feeds of the timelines for the participating projects?
    • We should apply some kind of review mechanism to approve news posts, articles, and so on

Examples

The documentation needs to be thorough, complete and informational. Examples and/or tutorials are the most important aspect for those getting into the projects, or starting to use them.

  • What
    • Along with the blog, this is the most important immediate aspect. We need good examples, and lots of them. Preferably wrapped up in dialogue that helps get the message across. We could use some structure for the examples, although the manner in which the Wiki hooks into the API docs will provide additional structure. Good articles can be written around a small set of examples.
  • Where
    • Probably at same site as blog, wiki can be used as a sandbox for creating new if needed
  • Who
    • Important job. Abraham and Charles have graciously offered their services. Please don't be shy about helping here.
  • License
    • Probably a public domain one? "This document has been placed into the public domain by xxxx"?
  • Formatting
    • Lots of opinion; but short examples need little formatting and much less documentation. Try to construct examples that are easy to follow and visually appealing (the source code itself). The latter may sound daft, but it's the same principal as trying to make a good first impression, or selling a house. Note that the use of tabs instead of spaces will often result in funky looking examples.
  • Extras/wild ideas:
    • Online compiler, put code in text field, get executable or object file back

Look and Feel

  • The trac look isn't the most popular, but should be skinnable at least to some degree
  • Lot's of opinions :)

Packaging

One important aspect here is to create a total, coherent package. The contributing projects need to put into a whole that is usable without further ado. This needs to be reflected in the provided docs, installation of modules and building of applications using the library(ies).

  • Installers:
    • Windows might use Inno which Charles is familiar with
    • Linux: .tar.gz and eventually contributed .rpm's, .deb's, .ebuild's etc.
  • Where, who, what, how

Hosting Options

We need somewhere to host the the different aspects, wiki, blog, project software and downloads

  • Options:
    • DSource for wiki and project software. Brad has graciously offered to host Drupal, if we wish to do that
    • Amazon S3 for downloads
    • External for blog and possibly wiki
  • We need Brad Anderson's understanding for most things related to DSource
  • Need to figure out whether Google Ads are suitable as a source of (partial) funding

Code Concerns

  • Common license: BSD
  • Selecting viable projects & portions thereof:
    • Ares
    • Mango
    • DDL
    • Build
    • ?
  • Suggested documentation conventions
    • License at top of file, along with author names, copyright text, revision list, etc.
    • Along with functions and methods, each struct, class, interface, or other aggregate should have some descriptive annotation. Each of these represent a good place to add short usage examples, using the ddoc "---" mechanism.
    • Ensure that only the expected interface is exposed by the API documentation.
    • Document each non-private enum-member, such that it will be included in the API documentation.
  • Suggested coding conventions
    • Use CamelCase for Module names. This permits more flexibility in descriptive naming, which is an important aspect of good documentation.
    • Capitalize, or use CamelCase for all aggregate-types and for enum member-names.
    • Use the "override" keyword appropriately. This will help make the code more robust in the face of long-term changes.
    • The default visibility of methods, attributes, members, enums, structs etc, should be private. Expose only what's necessary.
    • Make all imports private by default. Consider exposing those which would be required to invoke the primary function of the given module; such as the arguments to public class constructors. This makes pedestrian usage simple, yet helps to reduce namespace collisions and actually makes the compiler run faster.
    • When using default argument values, try to order them such that common usage has the least knowledge required
    • Avoid large numbers of parameters (6 and above?) where at all possible. If things start to get crazy, consider using a struct to gather related arguments instead; or try to partition the functionality.
    • Consider returning a value from all methods/functions. It's almost free! Call-chaining is one reasonable application of this idiom.
    • Please, please, please use spaces instead of tabs ;)
  • Possible extras:
    • Common code style (long term?)

New Name

Doc Tasks

  • Work on a template for MediaWiki?. A simple example is over here: http://www.hula-project.org/Hula_Project
  • Research a custom template for the CMS page
  • All primary doc content will be placed into the Wiki. Drupal will get copies and or links for published articles and so on
  • Get basic CandyDoc? API stuff up and running, so there's a foundation to construct some Wiki links around
  • Create examples with doc. Organize in a progression of simple to the more esoteric
  • Populate overview information on the various library packages, starting with common stuff, such as file IO and console output?
  • Write a Tango install guide
  • Fully document the library APIs, perhaps by examining the CandyDoc? pages and filling in as we go
  • Whack the tango.store documentation into shape
  • Consider writing an install program, to sweep for updates from various places
  • Get a code highlighter installed or configured
  • Make a bunch of basic step-to-step tutorials for beginners (How to install D-compiler, How to make a library, etc..)
  • Think about translations

People, and what they are Offering

  • Kris ~ library code and API documentation; some examples; possibly an article or two
  • Sean ~ ditto
  • Lars Ivar ~ DDL stuff, Linux testing
  • Kyle ~ CMS/Blog, CSS/XHTML, PHP/MYSQL customization
  • Charles ~ Potatoes
  • John R ~ Examples, Articles, Tutorials, Debugging; Cheering section; coffee (not Java) and bandaids
  • Abraham ~ Examples, french translations
  • Eric A ~ web stuff, graphics, CMS extensions, testing and rhythm guitar (on top of DDL et al)
  • Brad A ~ admin, hosting, web stuff, testing, recreational pharmaceuticals
  • Juanjo C ~ library code and documentation, possibly examples, hosting if needed, Linux-only (sorry, but I'm not going back to the dark side)
  • John C ~ locale code + documentation, perhaps an article about localisation
  • Victor ~ CandyDoc? updates