Re: Writing down design documents

[Justin Emmanuel]

Agreed,

I mentioned something like this some time back. I asked also if there
was some sort of graphical way that these ideas can be represented. I
got no answer at the time although I think that it would add immensely
to the clarity and help people come into the project and get plugged
in quickly. Since then, I have stumbled upon one possible graphical
tool that I have found personally very useful - Freemind from
http://freemind.sourceforge.net/wiki/index.php/Main_Page
You might want to try it out. Use of this plus any standard
documentation methods.

For me, I find that since the thought process itself is not linear.
The most natural way to lay down ideas fast then work out how they
link together is not going to be something that starts from left to
right then top to bottom. But is based on ideas linked by their
relationship to one another. I don't know how many times you guys have
had to explain capabilities.. Then people get directed to some
documentation over the net, they come back, then still need
clarification!! A good graphical tool can show neatly how all these
things fit together. It would also help with traditional documentation
as it will be clear what needs to be written up. Just make sure that
every node is explained.
Using a tool such as Freemind (Or any other that would do the job)
Will also allow for additions and tweaks to be easily added and
relationships to be altered.

I cant agree more with what Pierre has stated. I would like to know
what the maintainers think. There probably is loads that has already
been decided. But without the documentation, people sometimes think
that nothing exists.
As we know ideas are subject to change (especially here:) A graphical
tool can help organise that process and show that the whole script is
not being changed just one part.

These are my thoughts.

On 14/04/06, Pierre THIERRY <address@hidden> wrote:
> Hi,
>
> I'd like to advocate here for some work on all that has been said on
> this list the past months. There have been passionate discussions, some
> with a clear consensus at the end, some not. There have been
> explanations on concepts, design decisions, desirable properties and
> features, some clear and pedagogical, some not. ;-)
>
> But all of this, at the moment, is scatterd in the mailing list archive,
> which is all but convenient to read. When you want to understand
> something, you have to replay by their begin all the discussions on it.
>
> So why not write down some documentation about what we are discussing
> here, to make it easier for newcomers to grab the situation when they
> want? (and for the others to refresh their memory when they need)
>
> Here are the main documents I'd like to see to find information quicker:
> - Design principles
> - Concepts (things like POSIX, capabilities, etc.)
> - Subsystems
>
> The main part would be the latter. There could be pages where the
> consensus found is explained, along with the alternatives. For complex
> problems, maybe the design and the rationale should be separated.
>
> Could the main contributors of the discussions state if they agree or
> not on this idea? I'd like to help on this particular point, so I'm
> willing to try to write at least stub pages and begin to fill them with
> what has been said on the list, but I don't think it's even feasible
> with the help on the authors of the ideas...
>
> Documentally,
> Nowhere man
> --
> address@hidden
> OpenPGP 0xD9D50D8A
>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.2.2 (GNU/Linux)
>
> iD8DBQFEPw5Pxe13INnVDYoRArOKAJ9R2DakK2ehrUfQ89kxuXLEjJlC3ACgj5Ht
> YXCjq4P69DgNM1u065Zsfhk=
> =osVF
> -----END PGP SIGNATURE-----
>
>
> _______________________________________________
> L4-hurd mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/l4-hurd
>
>
>