Thanks for the great feedback!
Jeremy Ruston wrote:
> I’ve also been thinking about something similar: using TW5 to create
> a reusable tool that interleaves documentation files in a standard
> git repository, threading them together to construct a TiddlyWiki that
> can be used to view/edit the docs, or to generate static renderings.
> I think the round trip editing could be a killer feature: most
> existing documentation-baking tools expect editors/writers to navigate
> the source tree of MD files directly.
Ah, I think I forgot to mention that I was planning on the standard view
of this to be read-only. :-)
What you're talking about sounds like a terrific extension of my ideas,
and I had considered some of it. I was thinking that core team members
might be able to edit the tiddlers in place for a round-trip experience.
But that was not central to my idea, and definitely was not meant for
a first pass.
Although I love TiddlyWiki's save-in-place mechanism (now slightly
altered for me by running with Node, but still awesome), this has little
to do with my reason for using TW in this case. The point was the UI
that TW presents: the microcontent, the ability to have open just the
content I want, the ability to link to that collection of open tiddlers.
Your notion, though, is making me think again. I was considering TW
only as an output format that I generated from server-side markdown
files. Inverting that so that the microcontent is the main source of
truth would probably be easier to do. The trouble is that this library
will be maintained by a reasonably large community, and I also really
like the idea of a workflow that involves something like: change one
test file, one source file, and one markdown documentation file. Most
people working with this will be familiar with the standard way of
doing things in GitHub, which means Pull Requests from one's own copy of
the markdown files to the central one. That doesn't seem to mesh well
with using TW as the source of truth.
So I'm torn.
> To your specific question about whether the documentation files might
> be sliced into multiple tiddlers as part of the process of threading
> them together, I suspect that that might make it a little bit harder
> to make a round trip editor. There’s also the question you raise about
> whether chunking into sections will actually lead to reusability.
The thing is, there are parts of this I definitely want at some point to
be able to reuse. For example, I really would like to be able at some
point to search the Signatures section.
I don't know if those Hindley-Milner-inspired signatures mean anything
to you, but to those using libraries like this one (or like Ramda or
Sanctuary) and to those from many FP languages such as ML and Haskell,
this is simply how functions are described. Haskell, whose
documentation overall does not impress me, has one killer documentation
feature: Hoogle. This API search feature lets you specify a signature
and it finds all the functions that match, in various ways. A search
results page for `(x -> y) -> [x] -> [y]` not only returns the `map`
function for lists (`map :: (a -> b) -> [a] -> [b]`), but also for more
generic types (`fmap :: Functor f => (a -> b) -> f a -> f b`) and more
specific related but not quite compatible types (`all :: (a -> Bool) ->
[a] -> Bool`). You can see these and many more at
<https://www.haskell.org/hoogle/?hoogle=%28x-%3Ey%29-%3E%5Bx%5D-%3E%5By%5D>
I think I might be able to make something like this, but only if I have
a way of distinguishing the signatures from the rest of the the
documentation.
And there are a few other similar ways I might want to use this
microcontent.
> Perhaps there’s more scope for reusability by centralising definitions
> and descriptions, and transcluding them at the point of use?
I would definitely centralize what I could. But that sample I supplied
before was all specifically to do with the function `map`. Like with
Ramda, there are some core concepts that might be mentioned many places,
but those would probably be with links. The point was not that these
API pages would use external content, but that other documentation might
use pieces of these pages.
> Anyhow, it’s all quite ambitious, but one could build it in stages:
> * An MVP to get things started might be a tool that scans a repo for
> documentation files and does the most basic aggregation of those
> files as tiddlers into a TiddlyWiki that includes a plugin
> containing the templates needed to view and interact with those
> tiddlers
Yes, that would definitely be my first pass. And doing that does not
concern me at all. I think I can do this quite easily with Node. I
can also split the content the way I was suggesting; I'm just still
not sure whether doing so would be a good idea.
> * Next, one might try to get things working under Node.js so that the
> documentation files can be edited within TiddlyWiki. There would be
> a startup process reading the tiddlers from the repo, and then
> passing them to the syncer/filesystemadaptor so as to have future
> changes to those tiddlers synced back to the original file
This sounds much more complex. I'd have to think about this quite a
bit.
> * Finally, one could explore reusing some existing open source
> documentation templates for output
To my mind, I would only design two ways to view the documentation:
The TiddlyWiki would be exposed and viewable, perhaps both in a
read-only mode for most and an editable mode for the maintainers. And
the plain markdown files would be part of the repository, viewable
through the GitHub UI or locally through whatever Markdown viewer you
choose.
----------
I guess there is one other possibility that I hadn't really thought
about. If the GitHub markdown is the source, I could generate tiddlers
with a newly-created content type, and move all the structured data from
the text of the tiddler into data fields. That would presumably make it
easy to add the sort of searching I want and to reuse the content
elsewhere. Are there downsides to this that I'm not seeing?
Cheers,
-- Scott
--
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit
https://groups.google.com/d/msgid/tiddlywiki/a99aa557-2a39-4a4c-b031-668826f487f5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
