Refresh documentation

[mikegoatly]

The LIFTI documentation has become a bit too much like an API reference manual, and I don't think that's the best way to structure it. (There's nothing wrong with having API references as well!)

I think having something a more scenario or recipe based might be a great way to explain to newcomers the different sorts of things they can achieve and expect.

[kemiblueoyes]

@mikegoatly I may be able to help. Can you give me an example of the documentation structure you'd want for LIFTI?

[mikegoatly]

Thanks @kemiblueoyes!

I'm thinking of something like the Panda's cookbook, except each example would be a short, concrete example of how to configure an index given different starting requirements.

There's a lot of things one can do to configure an index (see the subsections under Index Construction), and having some scenarios that cover each of them would allow people to scan through a single page and get some usage ideas faster than having to read loads of API documentation.

The closest examples I can give you are the Getting started pages.

The documentation is in this repo, as a hugo site under docs.

Does that help?

[kemiblueoyes]

Hi @mikegoatly . So sorry I didn’t respond until now. I got tied up on another project.

if you’re still looking for doc help, please let me know.

I looked through Lifti docs.

Did you want the current docs changed to cookbook format or did you want to create a page of recipes in addition to what’s there already? It seems like the current API reference format is useful but could use some updates to include recipes.

[mikegoatly]

@kemiblueoyes No problem at all!

I think API docs are valuable in their own right, but they don't help people get up to speed quickly, or give real world examples of where LIFTI might be useful. I think that's where recipes come in. So having a separate section to cover this makes sense. Possibly in the "getting started" area?

It might be worth considering linking from the APIs to particular recipes if they are particularly pertinent, but let's see how they shape up first.

[kemiblueoyes]

@mikegoatly yes, it would be good to link to APIs where applicable.

Do you have a list of recipes you wanted to start with? And will this be a growing list that others can contribute to?

maybe instead of adding the cookbook to getting started, we add a new cookbook page instead and link to it from the getting started page? What do you think?

[mikegoatly]

Very happy with the suggestion to have the cookbook section separate!

As for ideas for recipes, perhaps we could start off with some simpler ones to break people in, e.g.

• Indexing loose text (Similar to what's in the Getting started)
• Indexing an object with properties (Similar to Indexing Objects but possibly skip the stemming configuration)

And then work to more complex scenarios - some past issues could be used as a basis for them?:

• Dynamic fields
• Score boosting
• Nested objects
• Ignoring specific characters in text

I'm sure some of the other old issues might offer some starting points as well, but that's more than enough to start with!

[kemiblueoyes]

@mikegoatly Let’s start with the summary on the cookbook page and the two recipes for indexing loose text and indexing an object with properties.

But, before we begin, could you answer the following:

• Do you imagine this cookbook to grow over time? We need to consider how to organize for scalability if you think you'll constantly add recipes over time.
• Are we going with the ones on the Getting Started and Indexing Objects pages as they are, or do you need to update them first?
• I haven't used hugo, so have a couple of questions: I've forked the repo. Will you create the cookbook page and then I can fetch, branch, and create pull requests?

[mikegoatly]

@kemiblueoyes I've created a branch called recipes with a placeholder page for the root of the recipes:

The documentation automatically pulls the level 2 headings to a secondary navigation menu on the side, so in the short term do you think having them all on the same page works? Alternatively creating a page per recipe within the Recipes folder would also work as the index page will list them with their short descriptions, similar to this:

Let's definitely start with those two ones as they'll help us form the content around something simple, and we can grow it from there.

Thanks again for offering to help!

EDIT: In that branch I've also added some "contributing to documentation" guidelines in the README to help you get up and running with hugo. Let me know if it doesn't work, or that needs further clarification as well!

[kemiblueoyes]

@mikegoatly Yes, in the short term, it's fine to have all recipes on one page. Maybe let's start there until we know what it looks like to have the first 6 recipes mentioned previous added to the main recipes page. Then we can consider that having a page per recipe makes sense.

In other news...
I tried to run hugo locally following the instructions on the readme but get the following errors (see image). And, I need to initialize the docy theme in the main docs folder and not the docs subfolder such as /docs/content/docs, right?

[mikegoatly]

@kemiblueoyes yeah, /docs is the right location to do it from. I think you just need to pull my branch over and switch to that. While I was creating the branch for you I noticed that something was broken in the docsy theme and worked around it there.

[kemiblueoyes]

@mikegoatly It looks like the vendor folder for Bootstrap is missing because when I comment out the code that is trying to get vendor/bootstrap/dist/js/bootstrap.bundle.js, most of the error messages disappear, and I can't find the vendor folder with bootstrap anywhere. Where and how can I get it?

[mikegoatly]

I'm not at a computer with LIFTI available to it, but looking at the doc folder here, there's a package.json file which suggests you probably need to also run npm install - does it help when you do that?

[kemiblueoyes]

Yep. That worked. Thanks @mikegoatly

[kemiblueoyes]

@mikegoatly I’ll start writing the draft for the summary on the recipe page and the first recipe today.

Meanwhile, I think once the recipe page is up we should update the Getting Started Page so that one, the content isn’t redundant, and two, you provide information to developers they typically expect in a Getting Started page: what they need before they can start using LIFTI, installation, environment set up, dependencies, and so on. Let me know your thoughts on this.

[kemiblueoyes]

@mikegoatly I sent a pull request for the draft of the recipe page. Let me know if you want a simpler recipe or have any other thoughts or changes.

[mikegoatly]

Thanks! Sorry, work is a bit full on at the moment - I'll try to take a look at this tomorrow!

[kemiblueoyes]

N worries. Take your time with the review.

[kemiblueoyes]

@mikegoatly, I see you merged the pull request. Are any updates needed? Comments, thoughts, next steps?

[mikegoatly]

@kemiblueoyes Sorry for the delay! I've taken a closer look at the recipes and pushed some suggestions to the branch.

I think the purpose of this is to give people a quick jump-off point for something that they might want to do. I wonder if it will be easier for developers new to LIFTI if each recipe was a simple, self-contained code block, e.g.:

For each of them I've put together (and linked) a working .NET Fiddle that people could play with straight away.

I'm not totally sure about the wording around the scenarios themselves yet.

What do you think?

[kemiblueoyes]

@mikegoatly If this is the route you want to take, that's fine. I sent a pull request. I just added the descriptions from the original version for each code sample. You can follow that format for the rest.