Hello All, I agree with Bill here. I think the document sources (source-x.adoc + images, icons etc) should reside with the branch / tag etc. The only problem I see with this is how to build them on Windows if we're sticking with AsciiDoc as the markup language. Linux is not a problem.
We can easily create additional folders / locations for each version / branch, but it would be nice to have everything located together. Having said that, do we really need a User Guide for RC / Dev branches or would it be best to simply release the manual when a formal release is published, thus maintaining just one manual per application. See additional comments below. On 4/7/2015 8:21 AM, Bill Somerville wrote: > On 07/04/2015 14:51, Joe Taylor wrote: >> Hi all, > Hi Joe, >> >> We need to make a policy decision about how we store the source files >> for our User Guides. >> >> For WSJT-X the sources are currently found in these SourceForge directories: >> >> .../branches/doc/wsjtx/source >> .../branches/doc/wsjtx/images >> >> This system has worked well in most ways, but does not readily >> accommodate the fact that we currently have three active versions of WSJT-X: >> >> WSJT-X v1.4.0 - about to be cleared for general availability >> >> WSJT-X v1.5.0 - standard development branch; beta release soon >> >> WSJT-X v1.6.0 - leading edge branch for incorporating the >> VHF/UHF/Microwave/EME modes supported in WSJT > The natural approach to this is to have the manuals sources as part of > the product sources, that way they can be branched, merged and, tagged > automatically in line with the product. Having said that manuals do > present a special problem with source control merging since they tend to > be bulk updated and do not merge very easily. +1, this is where I think they they should reside also, but I agree, merging could present problems, especially with the binary images / screen shots etc. > > Also incorporating the manual sources into the product sources means > that the manual build steps need to be added to the product build scripts. For other projects, FLDIGI for example, this function is part of the Makefile system. However, the FLDIGI project cross builds the binaries on Linux to produce the NSIS installer for Windows. For what it's worth, they too use AsciiDoc as their markup language. >> When we start to write new User Guide sections for v1.5 or v1.6, I guess >> we'll need a new branch (or branches?) to accommodate them. Should we >> make a v1.4.0 tag of the doc branch as it stands now, and call that the >> "final" v1.4 manual? (Or should it be a branch, rather than a tag, so >> as to make more obvious the possibility that further >> additions/corrections might be made?) > Branching the manual sources independently of the product sources can > work, using matching branch and tag names to the product can help a lot > with navigating. It can work, it does now, but I don't think it's the right place. The doc's should be part of the branch source code. > > It might be worth changing the terminology in the WSJT-X help menu to > have the local file system version of the manual as the product manual > and the on line version as a latest version preview i.e. not version > specific. If the decision is to keep the doc sources separate from the app sources, any number of ways could be implemented to accomplish the separation. >> >> The current .../doc/... branches (the ones listed above) would then >> become the place for v1.5 additions and updates to the manuals. We'll >> need to use distinguishable, version-specific file names in the URLs >> used for their online access. > Version specific file names are also necessary for the WSJT-X build so > it can bundle the correct manual version with the application. >> >> Does this make sense? Other suggestions? >> >> -- Joe, K1JT > 73 > Bill > G4WJS. ------------------------------------------------------------------------------ BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT Develop your own process in accordance with the BPMN 2 standard Learn Process modeling best practices with Bonita BPM through live exercises http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual- event?utm_ source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF _______________________________________________ wsjt-devel mailing list wsjt-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/wsjt-devel
