Documentation Brainstorming

What is brainstorming?

Brainstorming is the process of gathering and writing down all the ideas that people have about a given topic, whatever they may be. No idea or thought is too minor, too vague or too problematic to be rejected; the point is to gather as many ideas as possible and decide later if and how they should be worked on.

How should I add an idea that I've brainstormed?

There's no fixed format for a brainstormed idea; you can simply write down whatever comes into your head (remember, no thought is too minor, vague or problematic!) If you can, though, try to make it as clear and concise as you can. For the purposes of helping others think about your idea, you can also add more information about it. In this context, things you might want to include are:

• A short statement of what the idea is;
• A short statement of what motivates that idea, including any references you may have to other thoughts or discussions about it (e.g. to the ​mailing list archives);
• An outline of what you think the ramifications might be;
• An outline of it might be implemented; and
• (entirely optional) your username or other information so that people can contact you about it for further discussion.

What if I'm not a committer?

Non-committers can now edit this wiki as well, since May 8 2008.

Ideas brainstormed so far

• Update the DocBook-related ports so that they can be more easily used to validate and transform DocBook files; it's been proposed that we once again use DocBook as our offical documentation format (I'll add a link to the discussion on macports-dev later). The problems with the current ports are:
  • they don't include V4.4 or V4.5 of the DocBook standard;
  • the naming scheme largely doesn't mention the version numbers;
  • not all the ports automatically update the local XML catalog so that DocBook DTDs can be used offline.
  (Added by boeyms)

---

• Regenerate the old Darwinports faq and documentation and put it on the current site so that people can refer to it in the meantime, since the old server has gone dark. (Probably has been discussed on the mailing lists somewhere.) (Added by boeyms)

---

• Create a user wiki that enables users to log in and edit user-provided HowTos and so on, separate from the official MacPorts documentation, and without having to apply to portmgr to get commit rights as is the case for the current MacPorts wiki. (Will add link to discussion about this from the mailing lists.)
  • Potential problem: wiki and comment spam
  (Added by boeyms)

---

• • We need somebody with the vision, drive, and determination to fix the documentation end of things, including pursuing one of the options above. Portmgr would love to hear from you if you'd like to pull this off.
  • We really need a nicely designed front-presence that describes the project and gives access to ports and documentation. Our current front end does those things only marginally.
  (Quoted from [http://lists.macosforge.org/pipermail/macports-dev/2007-May/001579.html post to macports-dev by jberry])

---

• Make the code self-documenting (perhaps in docstring style; Wikibooks has ​an example of how to do this in Tcl. (Added by boeyms)