I am new to this forum and I write software, thus also software manuals

Hi,

I just found this awesome Scrivener and it has the potential to become my new tool fow writing my manuals and video project scripts.

Since 2000 I started a project that is more likely running in the niche of software development itself. It is a very specific piece of product and I struggle to get a manual that is

A) Multilanguage
B) Easy
C) Didactical

and having accompaning video material for those, who like this medium.

I think, I’ll get these issues solved and even much more. My documents are written in OpenOffice and I have simply no strait translations from english to german. Yes, I have a english first

What I think, Scrivener could be used for the multi language issue, is using labels. But I think it could be conflicting with the concept and chapter values and thus the purpose of this field is not really qualified to be used to set a language.

So here is my first question: Can I add a column (language)?

I want to have easy tutorials to get out of my documenting project. In a plain word processor, this is more or less a poainful job. Here I think the export feature is great. Especially I just looked at the export possibilities (project presets), that may help me producing several documents from easy to any deeper level of experience.

Is that the right direction I should go in trying the feature for this requirement I have?

The last, didactical, may be a complete handbook and will be the most complicated job (except vlogs and video stuff creating).

Is it a good idea to have one Scrivener project for all these points?

Now I have some ideas to my documenting project.

I like to also have a multimedia project (script and some prototypes of video ideas / paintings or scribbles). What I mean by this is keep track of my chapters and accompaning video tutorials that I am also developing. Currently I simply created some without really planning them with a script.

Who has experience in that area?

I want to push my open source project and therefore I think, also a good vlog or youtube channel may make sense. Currently I just have one channel, but that is not too focused. Also I am running a patreon page that is not well working

So I really need a tool that also helps me into that direction: Multimedia content but with corresponding writings or accompaning docments.

Modification 1:
At the end, I also need to start financing my project. It has some cost to simply underestimate it. How about this Amazon self publishing service offerings?

Who has experience in this area in conjunction to writing manuals and the like?

What do you think?

Big project?

Thanks,

Lothar

Welcome Lothar.

I’m not sure I can help you with much of what you ask, but I can, I hope, on the ‘two language’ question.

I work as an editor for Chinese–English translation, where the texts are very often interleaved Chinese paragraph followed by English paragraph. I have found that the solution is to split it up into separate language documents, labelling them respectively as Chinese and English, and then setting up “Chinese” and “English” collections based on their respective labels.

I then use a split editor, loading the collections as “Scrivening” sessions in each split. That way, I can have the English text I’m editing on the left and the Chinese source on the right.

When I’ve done my work, I simply compile the whole draft, which is still in its original interleaved order, and send it off.

All I use are labels and collections. Setting it up is what takes the most time; after that it’s plain sailing.

If you’re not working with interleaved text, then you could have the English and German as separate sub-documents of the whole, and simply assign one of the editor splits to each language.

Hope that helps.
Mark

Thank you,

that was a help. I find the sub documents a valuable feature, if I have understood that correctly - they are simple folders.

I haven’t yet found the collections more usable than adding sub folders in the script folder, in your case - keeping the original structure, it may be the solution after splitting and labeling. There is a bit setup time ahead, that I could understand.

In my case, the folders within the script folder will be a starting point. I created an english and a german folder. Within these folders I have created a book and a flyer folder respectively. (The flyer stands for some short version text per document. It may also be a / some scenes)

Using the collection makes sense, if I select all german flyers into one collection and all german book documents into another. That way I am not only able to translate a book, but also create flyer content out of (selected) book documents.

That way, I got my translations managed, the point easy is tackled (Flyer => short getting started content) and didactical may be tackled.

Video content could be worked on by adding another collection with the derived scenes / script.

I think that this application is a very good one

What I do not really like is the research folder and putting files into it. Can they also be linked instead embedded?

Yes, you can use “aliases” rather than importing. See File > Import > Research Files as Aliases… — this works great for many formats but not all (for example excel files, where you need to get creative with importing an alias created in Finder of the excel file as the alias!!!)…

There are many ways to do the the same thing in Scrivener, and I consider its flexibility its greatest strength! If you create software manuals, I can recommend looking at the source Scrivener project of the scrivener manual itself, there are lots of advanced tricks that can be useful for you.

literatureandlatte.com/support.php#Scrivener

Thanks,

a real example is of course the application documentation itself

Also I need to consider using my version management system (currently still CVS). That way, I can keep up the documentation in sync with the project. If the project structure itself is too complex for CVS or Git, what I don’t think, I could consider plain text export and sync. I found that feature from an article about collaborative writing: cultofmac.com/291161/draft-s … e-writing/

That way I can share my work to anyone by just pointing to that draft thing 8)

I’ll buy it now :mrgreen:

I have tried the manual source project and at least was able to read it and produce the multimarkdown output that collects all images and writes one markdown file.

I am aware of it to require post processing and I have installed the package version of mmd and gave it a try. I failed to get the same results as of the included PDF file

There is surely something missing, one may be the LaTex markdown support files. Do I simply have to copy those from Git into the recommended folder?

What else do I need? I assume I have to always invoke mmd after compiling.

Also the compiled HTML file did contain both, the Mac and Windows parts (example: About this Manual - four / five).

Does the included XSLT template filter these elements, or does it do more?

I probably would include a make process into my software project to convert the mmd with some commands, if it changes. I’ll be able to automate that.

For anything more about mmd, I’ll refer to the Multi Mark Down area in this forum.

Well with the Scrivener manual project, that is an old project and it depends upon an archaic version of MultiMarkdown (2.x). When I compile from it, I have to compile to plain .mmd, and then run that against an archived copy of MMD on the command-line, which is really slow because that version was written in Perl and a huge snarl of regular expressions. Then once that is done I have to run through about a 40-point checklist in a text editor, cleaning up the .tex file in ways the XSLT or MMD itself can’t do automatically, and finally it’s ready to be turned into a PDF.

There was no such thing back when it was made. The XSLT is solely responsible for assembling the .tex file.

So I wouldn’t exactly recommend the post-processing experience as being anywhere indicative of what a modern streamlined project could be instead. For that, the downloadable Scapple manual is a better reference example. It doesn’t use any XSLT in fact—all of the “stylesheet” is built right into the compile settings, and with a few additional .sty files and fonts installed into the LaTeX distro, you should be able to get close to the PDF that comes in Scapple (a few of the branding graphics will be missing). (One caveat, since Scapple hasn’t had a feature update, it’s been a while since I’ve tried compiling the project.)

Yeah that is handled by XSLT in the Scrivener manual, and by LaTeX commands in the Scapple manual. Neither is meant to do anything but produce .tex files, frankly.

Now, as for what the next manual will look like—well, let’s just say the next version of Scrivener will make the current version look primitive in terms of technical output capability. I can’t go into detail, but a lot of stuff that I’d consider to be hacks in those .scrivs are now natively addressed, and a lot of stuff that needed extensive 500 line XSLTs or whatever, and LaTeX-side logic control are now built directly into the compiler. I do still use a little ten line or so Ruby file to clean up a few stray things Scrivener+MMD can’t do, but even that can be wired straight into the compile workflow now so that it’s part of clicking the Compile button. Good things coming!

Edit: I just have to read the project description! Just downloading MacTex and follow the description

I tried that with some compile options (mmd,PDF, …), but either there is some XML comments in the text (not processed - ODT), or there is no page layout (plain RTF, I think). I am a dumb beginner

So, currently the ODT format gave me the best page layout and even the tip boxes are handled well, the only problem there is the missing XML comments that need to be converted. Will this be done by the sty files and fonts? Where do I get these files? If they refer to fonts, I’ll probably able to replace them with my set of fonts to be chosen. (I am thinking to select my website font from the logo for the headlines and a matching complementary font to be defined: lollisoft - using the headline font all over the text was not a good idea)

I think, I should not yet start with worrying about the output format, font and style. But rather keep going with my application documentation to be imported as a starting point. When will be the new version available? Do you have a roadmap?

Just to point out to my document. There may be still some pre work about the content order and other stuff before even thinking about a nice formatted software handbook. It is more complicated than only describing all the application menus

The following link will download the PDF file from my sourceforge project: My writing

I’m not sure what AmberV’s next gen workflow will be, but you should also seriously consider Pandoc instead of MMD if you want to maximise your flexibility. According to existing info, the next version of Scrivener (3) will support pandoc directly.

pandoc.org

Pandoc is created by a working philosophy professor, and is very actively developed by many others. It is used in many different fields and therefore caters to many use-cases. Pandoc represents documents into a universal internal structure, letting you write very elegant filters to make complex transformations simple (less need for complex fragile regexes). These filters let you represent markup to make custom output so you can generate really specialised documents. There are very cool wrappers which take a YAML metadata file and flexibly handle multiple pandoc workflows:

github.com/htdebeer/pandocomatic
github.com/msprev/panzer

If I was to make a technical manual (I’m an academic so personally have no need), my workflow would be Scrivener > Pandoc > PrinceXML. I would choose PrinceXML over LaTeX simply because I think CSS is far most elegant and well documented than the archaic mess of overalapping TeX systems.

Other more modern (than TeX, not difficult!) layout alternatives:

github.com/simoncozens/sile — Sile is a modernised pseudo-TeX, and can work with Pandoc.
patoline.org — ???
wkhtmltopdf.org/ — this is supported by Pandoc, and could be considered the poor man’s PrinceXML.

The current Mac Pkg installer tells me, that it could not be installed on that computer. I still use my older Snow Leopard installation for programming and do less frequently change to Yosemite.

I’ll give it a try, maybe in the next some weeks. Meanwhile I need to find a Font, I probably could use on LaTeX and later on with PanDoc.
I have absolutely no idea what a good font is but I have requirements to the license: LGPL or compatible license.

The XML stuff in general seems interesting to me as a XML / XSLT user 8)

ヽ( ￣д￣)ノ Um… Um, sir? Is lollisoft the name of your company, or something?

I’m not sure if I should tell you, or let ignorance be bliss… It’s sort of, widely used internet slang… in the otaku communities, especially on the Internet.

Yes, my domain name and my usual pseudonym. It is my nick name lolli and soft for software.