Comments (20)
@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.
from lifti.
@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.
from lifti.
@mikegoatly I may be able to help. Can you give me an example of the documentation structure you'd want for LIFTI?
from lifti.
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?
from lifti.
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.
from lifti.
@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.
from lifti.
@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?
from lifti.
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?:
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!
from lifti.
@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?
from lifti.
@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!
from lifti.
@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?
from lifti.
@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.
from lifti.
@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?
from lifti.
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?
from lifti.
Yep. That worked. Thanks @mikegoatly
from lifti.
@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.
from lifti.
Thanks! Sorry, work is a bit full on at the moment - I'll try to take a look at this tomorrow!
from lifti.
N worries. Take your time with the review.
from lifti.
@mikegoatly, I see you merged the pull request. Are any updates needed? Comments, thoughts, next steps?
from lifti.
@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?
from lifti.
Related Issues (20)
- Suggestion: custom stemmers HOT 2
- Search for words with a `=` character HOT 5
- Escaped characters in LIFTI query syntax HOT 1
- Q: is possible to fetch the whole document by Id? HOT 2
- Split IdPool and ItemStore HOT 1
- Consider switching to using ValueTask across the library HOT 1
- Operaterrors as a text HOT 3
- Standardize terminology
- Track source object type against a document's metadata
- Add a "not contains" query operator
- v6 documentation changes
- Create a standardised way of rehydrating an index from a serializer
- Write up implementing a custom serializer
- Apply field and document filtering when collecting results from IndexNavigator HOT 1
- Add README.md to nuget package
- Execution plans
- Consider dropping support for netstandard2
- How to nest queries? HOT 2
- Sign nuget package HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from lifti.