[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

On Wed, May 7, 2014 at 6:37 AM, Howard Trickey <howard.trickey at gmail.com> wrote:
> I would prefer a system where images are in git too.
> A mixed workflow where images go in svn and everything else goes in
> git would put a barrier to adding images that would, I think, tend
> to have writers not bother sometimes putting helpful images in.

Agree, I really like to avoid over-complicating the process.
just to note we can manage a few ways.

We could just migrate to git, and have a working repository where
history of unused images is flushed periodically (each release for
eg).
But keep a lager repo with full history.
... Or something similar where old images are archived.

This way the repo is kept small and authors are not bothered by details.

> Yes, I know the concerns about binary sizes, but maybe one could estimate
> this effect by adding up sizes of current images in the manual,
> and perhaps decide that it is acceptable.
>
>
>
> On Tue, May 6, 2014 at 1:59 PM, Bastien Montagne <montagne29 at wanadoo.fr>
> wrote:
>>
>> +1 for sphinx.
>>
>> I always had the feeling mediawiki was not really suited for a manual
>> (though some tremendous time was spent trying to make a bit more suited
>> some years ago). And I do not see the "easy to edit" thing as a wiki big
>> pro in our case (this tends to make editors way too much volatile, which
>> is not good in a manual context)…
>>
>> Just my two cents. :)
>>
>> Bastien
>> On 06/05/2014 19:34, Campbell Barton wrote:
>> > Hi, I wasn't aware of this list existing, but I was involved with the
>> > proposal to move the manual to a new system, will give some replies.
>> >
>> >
>> >
>> > @brita
>> >
>> >> Besides Manual, Dev and Tutorial also fit well in this scheme.
>> > Not sure about this. Probably we can leave tutorials to other web
>> > sites (there are many), and Dev docs Im happy to keep on wiki for now.
>> > Since they fit the scheme of random-linked-pages, much better. (as in
>> > - they dont need to read so much like a book).
>> >
>> > On the other hand, if this system works well, Im not totally against
>> > moving other parts of our wiki to it, But suggest to hold off until
>> > the manual has proven to be a success.
>> >
>> >
>> >
>> > @Jeffrey H
>> >
>> > Not sure what you mean about "linking" RestructuredText has a fairly
>> > nice method to add in cross-references and you can link to external
>> > sites too, I don't see this as an issue.
>> >
>> > but agree "user contributions" is a concern. There is the idea that
>> > making user contributions `easy` is the best way to get a document
>> > done,
>> >
>> > But IMHO the flip side of this --- is you get a lot of half edited
>> > pages, people start pages and dont finish them, and we get edits that
>> > probably should be reviewed or even rejected because of poor quality.
>> > Not to say editing documentation should be made difficult, just that
>> > the current wiki system has _not_ given us a really great manual IMHO
>> > (though parts of it are great of course).
>> >
>> > Currently we have a situation where docs are *broken* and thats
>> > considered normal, I think with a better system authors can be in a
>> > bit more control and not just have random 2.4x pages mixed in with
>> > 2.5x, 2.6x, 2.7x docs.
>> > However at the end of this day this is still work someone has to do,
>> > our-millage-may-vary :)
>> >
>> > Eventually I would like that the manual is a complete-document,
>> > covering areas of Blender in a clear & concise way, if something is
>> > incorrect or missing, this is reported as a bug/issue,
>> > it gets fixed before release, and we have some valuable resources we
>> > can include with Blender - basically manage this closer to how we
>> > manage Blender source code and releases.
>> >
>> > Your last point about using a wiki to supplement is well taken, but I
>> > dont think its unique to wiki's --- the manual can link to any
>> > external resource when it makes sense to.
>> >
>> >
>> >
>> > @marco ardito
>> >
>> > re - contributions, right, users can prepare docs on a wiki, on
>> > github, anywhere... then submit for inclusion.
>> > Since this is just a directory of files we're not locked into one way
>> > of doing things.
>> > For the Python API docs, sometimes I've just got mails containing
>> > improvements, but Id like if we had something a bit nicer.
>> >
>> > Expecting documentation authors to use git may be unrealistic, however
>> > github does have a way to edit text online and commit (without having
>> > to install git locally).
>> >
>> > Note that we aren't locked into git, if we find some other system
>> > better for authors, we can move to that too.
>> >
>> >
>> > Your point about a manual not just being a reference is important,
>> > some wiki pages in our current manual - list every button in a panel
>> > with their tooltips,
>> > In most cases i dont think this really helps, its not giving insights
>> > into how things work or showing users why they might use certain
>> > features.
>> >
>> > But I think this is orthogonal to which system is used, and am a bit
>> > worried if we try to migrate the manual to a new system at the same
>> > time as rewriting a lot, that it never gets finished.
>> >
>> >
>> > As for translations, while there is no special support for it (which
>> > could be nice to have), It could work out fine just to use branches,
>> > translators can review commits made since they last translated and
>> > update their versions if needed.
>> >
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-docboard
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
- Campbell