[Lumiera] Sitemap modifications

Christian Thaeter ct at pipapo.org
Thu Jul 22 05:33:29 CEST 2010


Ichthyostega wrote:
> Brian Rytel schrieb:
>> As I'm trying to progress with the 'new' website I noted a few minor
>> structure points to change and wanted any objections or suggestions:
> 
> 
> Hi Brian!
> 
> let me comment on some of your comments right here...

and a few comments from me ...

press/ looks like we running some company, pfft, i like propaganda/ more  :)

> 
>> * documentation/  //I propose to call this any of: reference, resources,
>> information or a synonym of your choice, so that this section doesn't appear
>> to be just user-manual
> 
>> ** media/    -- white papers, presentations, manuals
> 
>> ** technical/        //change this to documentation, as it will hold,
>> essentially instructions on the actual coding
> 
>> ** design/
> 
> in the time preceding this proposed website structure, this point was
> discussed to quite some extent. Maybe I should explain it a bit more.
> 
> the top-level folder "documentation" will of course also contain the
> user-manual. I think it's just an omission by accident in the current
> contents in website-staging. It figures that we don't have a user's manual
> currently, so for the time being "user-manual" would probably link to a
> page explaining that you can't use lumiera yet etc....
> Some time later hopefully this page might hold some tutorial showing the
> few things you can already do with lumiera then....
> 
> 
> 
> Then the distinction "technical documentation" vs. "design documentation"
> I must admit that this distinction is difficult to grasp for anyone outside
> the engineering camp. Just these two are present in any complete software
> documentation and are indeed /very/ distinct and different things. Like
> the birds eyes view versus discussing every nut and bolt.
> Also, several people proposed to have the sub sections within that category
> exactly similar -- personally, I disagree on that point, again because
> the design documentation and the technical reference are so distinct
> things, with such a different viewangle.
> 
> 
> Now, how to call the top-level folder? IMHO, "documentation" is the
> best choice, because it is the only precise and exact umbrella term
> which spans the user manual, whitepapers, the design docs and the
> technical reference, and just that and nothing else.
> 
> Well, I agree that "someone" might consider that "documentation" just
> means the user manual. Well, this might be a question of viewangle.
> This person could then open the folder and might realize that
> documentation is more than just a manual. Actually, I think,
> at that point, being precise doesn't hurt anyone.
> 
> Besides, there is the proposal with the page footer containing
> some important shortcuts to ease the navigation to fequently
> needed resources. So this footer might include "users manual"...

finally we want all documentation directly related to lumiera being part
of the source repository (we may convert it using git submodules),
someone who clones 'lumiera' should have a chance to get all he needs to
build the complete software, including its documentation (user and
developer docs). We are not that far yet, but we should keep an eye that
we want to merge all currently littered docs back to easily accessible
places and don't go back into maintenance hell having everything at
different places. This saied, a documentation/ folder on the webpage is
of course important and we want it, but finally it should either just
link into the main repos doc folder (when uwiki has a lumiera checkout)
or merge the lumiera documentation submodule in. Either way, this is for
the future, but important to consider this now.



> 
> 
>> ** design-process/            //the current contents need some re-arrangement
>> as some have been replaced by newer document. I think we should create a
>> system for organizing the Draft, Parked, & Final proposals
> 
> Yes, fully agreed.
> On the original system (Christian's moin moin wiki), we had a macro to
> accomplish just that. Probably it will be rather easy to get something
> similar when uWiki is ready.
> 
> But actually I see another concern here. Hopefully we'll continue to
> use this "Design Process", which then will result in a increasingly
> large number of final design process entries over time. So we might
> consider to move finalised pages completely away and place them
> elsewhere (probably most of these entries would be well suited
> as detail pages somewhere in the "design documentation"

woops .. i just written about design-process retargeting before reading
your mail. I may add to the old mail that the directory structure
(lumiera source, not webpage!) should be refined:
  doc/devel/rfc/    for final
  doc/devel/rfc_pending/{draft,parked,rejected}/

Btw: on the long run i'd like to keep rejected proposals, these are
valuable for anyone seeing rationales behind in some cases (some stupid
ideas might be just deleted, but sometimes there is a rationale why
something was taken down)


	Christian


More information about the Lumiera mailing list