I am between jobs at the moment (was just laid off). I have been a programmer for 25+ years. When learning new systems/languages/applications etc. I document what I am studying and learning (usually with MS Word). I also have PDFs, and eBooks, web links and so on. Topics range from MS Office, iOS, Android, C#, Javascript, Bootstrap and several others. I have also purchased or downloaded many books/tutorials with programming
I have always wanted something that I could use to keep track of all of this, particularly as I have PDFs stored in Apple Books, and Kindle’s.
Would Scrivener be a good fit for this type of project?
As described, I don’t think a good fit. Scrivener is a tool for writing and then producing delivery documents (in a multitude of formats). To keep track of all your material, you probably should be looking at a more complete organisation of the file system, or a database, or a speciality application. While not a direct recommendation as I don’t know more about what you are trying to do, but I keep all my reference documents, commercial e-books, and “data base” of my paper books in DEVONthink.
edit: if you are going to take on a technical writing project then it can work. All my work is technical non fiction. Scrivener is terrific. But it is not it a multi user team app as @Shell mentions. In the author/reader/editor world it works well for many regardless of fiction or non fiction.
I love Scrivener dearly, but for tech documentation, I’d use Notion. It’s much better-suited and cloud-based, so accessible everywhere/every device.
I write novels in Scrivener (Mac and iOS), but technical documentation lives in Notion (where multiple colleagues also contribute).
I see no reason not to do this with Scrivener. Many here are concerned that Scrivener can’t manage large amounts of data. I can’t confirm that. I have all my data in one Scrivener project. PDF, RTF, images, everything. Meanwhile this document is almost 2 GB. Very long text documents are a bit slower (over 20’000 words), but otherwise Scrivener handles everything without problems.
I can confirm what the manual says
“Scrivener can handle book-length manuscripts with ease, store large quantities of research material, and handle many thousands of individual components (…) Scrivener has been tested against projects with millions of words in them; way beyond what it would normally have to face. So for ordinary usage, you will never need to worry about limitations.”
I write a ton of technical documention. Right now in front of me I have a User/Developer manual for a very technical product. Scrivener is a great tool for its intended audience but I struggle daily with using it for this application. I am always on the lookout for nuances in this great software that will fit my usage requirements, so when I think something is difficult, I stick with the idea that I simply don’t know how I should handle it in a Scrivener way, rather than jumping to blaming the tool. That said, there are challenges that persist. Here are a few.
Global changes are difficult. Each document is an atomic unit and making some changes across groups of folders/sections can be a challenge.
Bullet lists are a pain to standardize. I just want to define a simple bullet list style and apply it to all bullet lists, but this seems to be elusive (as noted in another thread on the topic). I actually don’t want a “style” on lists, I just want each tab to move in a level and show a different bullet. Think Markdown. But Scrivener wants to be helpful with each such list at the expense of standardization of all lists across the project.
Scrivener preserves styling for content that’s dropped in. While we want it to preserve a bullet-list, for example, and perhaps justification of an image with text, We generally don’t want to bring in all of the fonts and sizes along with it. In such an operation we need to re-apply default styling to the inserted text, and this consumes just a bit more time.
I really love how we can create content with Folders, Documents with content that include sub-documents, etc. But I find myself figeting with these from time to time because Scrivener has specific ideas of what these containers are and how they separate content, where for editing purposes I consider the entire document a single entity and I just want these objects to faciliate reorganization. For example, we can have multiple text selections in different documents. Awesome! But I want to control that because I don’t want to forget about some selection, apply changes “to selection” and find out something was changed in a part of the document that I haven’t touched for a while.
Viewing an entire project as one long document is awesome. This is accomplished with the “scrivenings” view. We can select whether the document name appears in scrivenings mode - and the styling changes with the binding level: like H1 for folders, H2 for sub-folders, H3 for docs, etc. This is a great feature. But the document name is bound to the header. That is, a folder named “How to …” becomes the H1 header for a page, but I might want a different header for that section. “Why don’t you just rename the folder?” That’s the issue. I want a folder name to function as metadata to describe its content - not to be a part of the content. “Why don’t you turn off the auto-header and add your own?” OK, then I need to add manual headers to every folder and document. Why should this need to be all-or-nothing?
Consider those folder names. They are used as Windows folder names when exporting to Markdown and other formats. A folder name can’t be “How to …” due to the three dots. Assuming I actually do want those names to be a part of the content, now once again I’m faced with creating my own headers for every folder and document in the entire project, and not including the title in export content, or changing folder names because they are irrevocably linked to the OS file system conventions.
Again on OS names: Exported folder and file names include whatever characters you have chosen. Like the three dots (ellipses) that includes spaces and other characters. Here’s one in front of me “Change site/app. prefix”. I need to change my document name, and thus the title of the section to accommodate the fact that this won’t work with an export. In summary on this, if we know we’re going to export, then we need to use Folder and document names just like OS directories and files, with preference to not using spaces, care about casing, and not using characters like slashes, periods, etc…
Consider a Markdown export. In some documentation we just write a line of text and Enter for a new line of related content. We intend the equivalent of a <br>, not a <p>. In Markdown a simple end of line is ignore and we need syntax to describe our intent. So the Scrivener documents need to include a backslash at the end of such lines, or a double-space. This means our Scrivener source documentation needs to be aware of our intent for export to a specific external environment. To be fair, we can use any marker, convert that to backslash on compile for Markdown, and convert to null or or something else in compile for another purpose. We can say Scrivener gives us the freedom to choose how we want to do this. I’d prefer a more versatile compiler that recognizes the regex /$([A-Z])/ or similar (need to account for tabs and possibly other nuances) and convert that to /\n \\$1/ … or similar.
Again on export, and I’ll stick with Markdown: We can create a single huge document, any_name.md, and we’ll get the nice Markdown markup with folder names in H1 styling, etc. But if we want all documents to be in individual files, and the file names need to be OS-safe, then the single .md file with have those OS-safe headers. Ugh! A conscious choice must be made about how to structure a Scrivener project based on what we Might be doing with it in the future. This is not a concern for novelists and article authors, but is a real concern for technical writers who don’t know whether the final output will be a PDF, Ebook, MediaWiki site, HTML page, WordPress blocks - or maybe all of the above.
For technical writing we also need to be very careful about how code syntax is rendered. Will asterisks for multiplication rendered as bold text in export? Do we need to escape our source text to avoid that? Now it’s not just EOLs that are a problem, it’s code examples too.
To be clear, again, I love Scrivener! But it’s not meant for technical writers. All of the concerns above could be addressed in the product or with options that allow us to control the compile options better. Heck, there might be solutions to all of these concerns and I simply don’t know about them. The point is that this isn’t a bug list, it’s a set of concerns about how one must use this product as-is for a specific purpose, right now. Maybe the L&L folks will take this on as a challenge to support a new audience. I don’t think that will happen. They know their audience now and serve that audience well. I actually wouldn’t want to see this product messed up with features that are not useful to that audience as L&L seeks to increase marketshare. Other products have done that and paid the price.
Since we’re here I’ll summarize some of the above into feature requests:
Enhance folder/document naming to allow separation of the name used for OS objects from text used in documents. A document with name “Some Header” should support metadata with an alternate “some_header” name used for OS operations. Offer a default file name which is an OS-friendly version the current text.
Add Option to MMD and HTML export and compile to include or not include the document name as a styled header.
Find/Replace for a Project should allow for selecting text that has the same style as currently selected text - or some other way to globally change from one style to another. This is possible but it’s not intuitive.
For HTML export, allow for an override of the header styling block. For example, I might want all pages to be set to font-family Arial 12pt in the HTML, even if it’s Segoe UI 10pt in Scrivener.
I hope some of this helps someone - even if it means L&L can tell us “that feature is already in there!”
Excellent suggestions by all. I am familiar with DevonThink and have used it. I am going to research Notion and compare those two. Thanks to everyone for their replies.
Scrivener’s LaTeX template is really good and lends itself to easily produce well formatted scientific and technical deliverables. And a base to tweak if you want. Try it. Read the instructions in the doc above the “draft” in the binder.
I am using Craft on mac now for my note taking, which has its own markdown, creates beautiful looking notes and you can directly publish your notes to the internet and collaborate. i really like it for my personal note taking, but its subscription based which I don’t love. It’s also only based on MacOs, iOS and web. Does syntax highlighting and everything you would need to do for programming related notes. In my opinion it’s not good enough to be an actual blogging platform, though you could at least create documents there and export markdown on a file by file basis into whatever blogging platform you’re using. it has great ability to search for notes, organize notes into folders and categories, etc. And you can create multi-level documents with links that drill down into subpages, etc.
I am embarking also on a technical blog thing that will grow over time and I’m trying to decide whether to use Scrivener, but someone here just mentioned one thing that may be a deal breaker which is that I need to be able to have all my various blog posts and articles inside Scrivener as one large document with research notes and images, etc…all contained in there, but when I compile I need it to compile to a tree of text markdown files, suitable for a website. if it can’t do that easily with compile…if compile is truly going to always try to assemble the whole project into one humongous markdown file…then end of discussion, won’t work well for me.
Also for programming docs, the code block formatting built into scrivener is not really very good. You pretty much have to be needing to render to markdown so that a markdown processor can interject syntax highlighting and stuff like that.
